/*
 *  DataBuffer.h
 *  NetTalk
 *
 *  Created by Andrey on 14/10/2008.
 *  Copyright 2008 ИУ7-2003. All rights reserved.
 *
 */

/** \file DataBuffer.h
	\brief Файл содержит описания структур и функций для работы с буферами 
	данных в памяти.
 
	Структура буфера в памяти была создана для того, чтобы избавить библиотеку 
	NetTalk (и не только неё) от рутинной работы по созданию, иницилизации и,
	особенно, клонирования буферов и передачи их в качестве параметров и 
	возвращаемых значений.
 */

#pragma once

// Queues made "easy"
#include <sys/queue.h>
#include <KBaseTypes.h>
#include <KAnsiCWrappers.h>

/**	\struct DataBuffer
	\brief Структура, представляющая собой буфер в памяти.
 */
BEGIN_STRUCT_DECLARATION(DataBuffer)
	BytePtr data;
	//!< Указатель на данные буфера
	int	dataLength;
	//!< Размер буфера в байтах
	int currentOffset;
	//!< Текущее значение смещения указателя чтения/записи
	TAILQ_ENTRY(_DataBuffer) bufferQueueEntries;
	//!< Поле, необходимое для организации списков, элементами которых являются структуры DataBuffer	
END_STRUCT_DECLARATION(DataBuffer)

/** \fn DataBuffer AllocateDataBuffer(int bufferSize);
	\brief Функция, создающая новый буфер указанного размера
	\param int bufferSize -- размер создаваемого буфера в байтах
	\return Проиницализированная структура DataBuffer, ссылающаяся на выделенный 
	блок памяти.
 */
DataBuffer AllocateDataBuffer(int bufferSize);
/**	\fn DataBuffer InitDataBufferWithDataAndLength(BytePtr data, int dataLength);
	\brief Функция, предназначенная для «обвёртывания» уже выделенного блока 
	памяти структурой DataBuffer.
	\param BytePtr data -- указатель на уже выделенный блок памяти
	\param int dataLength -- размер выделенного блока памяти
	\return Проиницализированная структура DataBuffer, ссылающаяся на выделенный 
	блок памяти.
 */
DataBuffer InitDataBufferWithDataAndLength(BytePtr data, int dataLength);

/**	\fn void WriteToDataBuffer(DataBufferPtr dataBuffer, BytePtr data, int bytesToWrite);
	\brief Функция, выполняющая запись данных в буфер.
	\param DataBufferPtr dataBuffer -- буфер, в который будет осуществляться 
	запись
	\param BytePtr data --  указатель на данные, которые необходимо записать в
	буфер
	\param int bytesToWrite -- количество байт, которое необходимо записать
	\return Ничего.
 */
void WriteToDataBuffer(DataBufferPtr dataBuffer, BytePtr data, int bytesToWrite);

/** \fn DataBuffer CloneDataBuffer(DataBuffer sourceBuffer);
	\brief Функция, предназначенная для клонирования уже существующего буфера.
	Под клонированием здесь понимается создание создание ещё одного буфера,
	содержащего те же данные, что и существующий, и имеющий такой же размер.
	\param DataBuffer sourceBuffer -- буфер, который необходимо клонировать
	\return Проиницализированная структура DataBuffer, представляющая собой
	буфер того же размера и с теми же данными, что и исходный.
 */
DataBuffer CloneDataBuffer(DataBuffer sourceBuffer);
/** \fn void DeallocateDataBuffer(DataBufferPtr dataBuffer);
	\brief Функция, освобождающая память, занятую буфером
	\param DataBufferPtr dataBuffer -- указатель на структуру DataBuffer, память
	из под которой необходимо освободить.
 */
void DeallocateDataBuffer(DataBufferPtr dataBuffer);